=========================================================================
ISTRUZIONI e SPECIFICHE per WATOR
========================================================================

La directory WATOR comprende i seguenti file

$$ ls WATOR/

WATOR/README-2b
WATOR/gruppo-check.pl
WATOR/gruppo.txt
WATOR/Makefile
WATOR/out1.check
WATOR/testwator
WATOR/README.wator



-----------------------------------------------
Descrizione dei file contenuti nel kit
-----------------------------------------------

README-2b		: questo file


gruppo-check.pl		: uno script Perl che controlla il formato del file
			  gruppo.txt prima di effettuare la consegna
			  (NON MODIFICARE -- uguale al primo frammento)

gruppo.txt		: un file di esempio di specifica del gruppo
			  (uguale al primo frammento)
			  (solo 1 studente per gruppo)
			  (deve essere aggiornato con i dati di chi consegna,
			  secondo il formato esemplificato)

Makefile		: makefile per il test finale del frammento e la
			  consegna  
			  (NON MODIFICARE se non nelle parti richieste)


testwator 	        : script di test e output atteso su STDOUT
out1.check	

README.wator		: specifice del modello WATOR da simulare


------------------------------------------------
Cosa deve essere realizzato per "wator"
------------------------------------------------

Questo esercizio prevede la realizzazione di un simulatore multithreaded per
il modello WATOR (descritto in README.wator).

Il simulatore viene attivato da linea di comando con la seguente sintassi:

bash:~$  wator rows cols Sb Sd Fb NF NS [-t N]

Dove 

  rows      indica il numero di righe della matrice che rappresenta il pianeta
  cols      indica il numero di colonne della matrice che 
            rappresenta il pianeta
  Sb Sd Fb  rappresentano le corrispondenti costanti del modello WATOR
  NF        indica il numero di pesci presenti all'inizio della simulazione
  NS        indica il numero di squali presenti all'inizio della simulazione
  N         (opzionale) che indica il numero  di thread paralleli da attivare
	    nel simulatore [ se il parametro non viene specificato si attivano
            4 thread di default, inoltre N deve dividere esattamente "cols" ]

All'avvio, viene creata una matrice W di dimensione rowsXcols ed inizializzata
con NF pesci ed NS squali posizionati in modo casuale. Dopo la creazione
vengono attivati

* N thread "worker che si occupano di calcolare gli aggiornamenti di gruppi di 
  H=cols/N colonne adiacenti. In particolare, il thread 0 si occupera' delle
  colonne 0,1...H-1 , il thread 1 delle colonne H,..., 2*H-1 etc.

* un thread "visualizer" che si occupa di visualizzare il risultato di ogni
  iterazione quando tutti i thread hanno completato l'aggiornamento degli
  elementi delle colonne di cui sono responsabili.

Deve essere garantito 

1) l'accesso corretto (senza race condition) alle strutture condivise dai
   thread worker e dal visualizzatore (ad esempio la matrice W che rappresenta 
   il mondo)

2) la visualizzazione corretta di ogni iterazione (ad esempio tutti i worker 
   hanno aggiornato le colonne di cui sono responsabili)

La visualizzazione puo' essere effettuata sullo standard output in formato a
caratteri a scelta (ma specificato nella documentazione) oppure puo' utilizzare
il visualizzatore grafico presente sul sito del progetto. 

IMPORTANTE: Tutte le scelte effettuate (implementazione strutture dati,
gestione mutua esclusione ed eventi, formato visualizzazione su STDOUT etc.)
devono essere documentate adeguatamente o attraverso opportuni commenti nel
codice o (opzionalmente) in un documento separato (formato .txt o .pdf da
consegnare assieme ai file di progetto).

------------------
Come procedere :
-----------------

0) leggere attentamente questo README 

1) analizzare accuratamente lo script ./testwator e
   l'output atteso su stdout (file out1.check). 

2) implementare il comando 'wator' secondo le specifiche e testarlo
   accuratamente 

3) testare usando

       bash:~$ make test

  NOTA: (1) tutti i file sviluppati per la soluzione si devono trovare nella
  stessa directory WATOR/
  (2) E' importante che il test venga effettuato solo su
  codice ragionevolmente corretto altrimenti i risultati possono essere di
  difficile interpretazione, fuorvianti o inutili.
  
4) preparare la documentazione: ovvero commentare adeguatamente i file
   aggiungendo la dichiarazione di originalita'

   /** \file  ...
       \author Nino Bixio
     Si dichiara che il contenuto di questo file e' in ogni sua parte opera
     originale dell' autore.  */

5) aggiornare il file "gruppo.txt" con nome e dati

6) consegnare il file ESCLUSIVAMENTE eseguendo

      bash:~$ make consegna

   e seguendo le istruzioni. 
   Per la consegna e' necessaria l'utility "mpack" installata solo nelle
   macchine dei laboratori H, M ed I. Per consegne da altre macchine e'
   possibile scaricare il binario di 'mpack' dal sito del corso (attenzione:
   richiede che il mailer sia configurato correttamente.)


---------------------------------------
 NOTE IMPORTANTI: LEGGERE ATTENTAMENTE
---------------------------------------

1) gli eleborati non consegnati con "make consegna" non verranno accettati

2) tutti gli elaborati verranno confrontati fra di loro con tool automatici
   per stabilire eventali situazioni di PLAGIO. Se tali situazioni si
   verificheranno *tutti* gli elaborato coinvolti verranno annullati con
   conseguente perdita del bonus. 

3) Tutti gli studenti coinvolti in un episodio di PLAGIO comprovato dovranno
   re-implementare il frammento incriminato e saranno sottoposti ad una prova
   orale supplementare. In caso di recidive verranno esclusi dalla
   possibilita' di sostenere l'esame per TUTTO IL RESTO DELL'ANNO ACCADEMICO
   IN CORSO.

4) Chi in sede di orale risulta palesemente non essere l'autore del software
   consegnato in uno dei frammenti verra' escluso dalla possibilita' di
   sostenere l'esame per TUTTO IL RESTO DELL'ANNO ACCADEMICO IN CORSO.

5) Tutti i comportamenti scorretti ai punti 3 e 4 verranno segnalati
   ufficialmente al presidente del corso di laurea, che si riserva di
   decidere azioni disciplinari supplementari a quelle sopra descritte.

----------------------------
 VALUTAZIONE DELL'ESERCIZIO:
----------------------------

Gli studenti che consegnano una versione funzionante e ragionevolmente
corretta di entrambi gli esercizi del secondo frammento
entro la data di scadenza accumulano un bonus di 2
punti che verra' sommato al voto finale (vedi lucidi lezioni ed
esercitazioni).

La qualita' del codice consegnato per i due esercizi verra' valutata come
parte del progetto finale e contribuira' alla votazione assegnata al progetto.
Eventuali caratteristiche in piu' rispetto a quelle strettamente richieste
dalle specifiche date verranno valutate in questa sede.
